home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kregexpeditorinterface.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-09-10  |  4.2 KB  |  138 lines
  1. #ifndef __kregexpeditorinterface_h__
  2. #define __kregexpeditorinterface_h__
  3.  
  4. #include <qstring.h>
  5.  
  6. /**
  7.  *  A graphical editor for regular expressions.
  8.  * 
  9.  * @author Jesper K. Pedersen blackie@kde.org
  10.  *
  11.  * The actual editor is located in kdeutils, with an interface in
  12.  * kdelibs. This means that it is a bit more complicated to create an
  13.  * instance of the editor, but only a little bit more complicated.
  14.  *
  15.  * To check if kregexpeditor in kdeutils is installed and available use this line:
  16.  * 
  17.  * \code
  18.  * bool installed=!KTrader::self()->query("KRegExpEditor/KRegExpEditor").isEmpty();
  19.  * \endcode
  20.  *
  21.  * The following is a template for what you need to do to create an instance of the
  22.  * regular expression dialog:
  23.  *
  24.  * \code
  25.  * QDialog *editorDialog = KParts::ComponentFactory::createInstanceFromQuery<QDialog>( "KRegExpEditor/KRegExpEditor" );
  26.  * if ( editorDialog ) {
  27.  *   // kdeutils was installed, so the dialog was found fetch the editor interface
  28.  *   KRegExpEditorInterface *editor = static_cast<KRegExpEditorInterface *>( editorDialog->qt_cast( "KRegExpEditorInterface" ) );
  29.  *   Q_ASSERT( editor ); // This should not fail!
  30.  *   
  31.  *   // now use the editor.
  32.  *   editor->setRegExp("^kde$");
  33.  *
  34.  *   // Finally exec the dialog
  35.  *   editorDialog->exec();
  36.  * }
  37.  * else {
  38.  *   // Don't offer the dialog.
  39.  * }
  40.  * \endcode
  41.  *
  42.  * Note: signals and slots must be connected to the editorDialog object, not to the editor object:
  43.  * \code
  44.  * connect( editorDialog, SIGNAL( canUndo( bool ) ), undoBut, SLOT( setEnabled( bool ) ) );
  45.  * \endcode
  46.  *
  47.  * If you want to create an instance of the editor widget, i.e. not the
  48.  * dialog, then you must do it in the following way:
  49.  *
  50.  * \code
  51.  * QWidget *editorWidget =
  52.  * KParts::ComponentFactory::createInstanceFromQuery<QWidget>( 
  53.  *     "KRegExpEditor/KRegExpEditor", QString::null, parent );
  54.  * if ( editorWidget ) {
  55.  *   // kdeutils was installed, so the widget was found fetch the editor interface
  56.  *   KRegExpEditorInterface *editor = static_cast<KRegExpEditorInterface *>( editorWidget->qt_cast( "KRegExpEditorInterface" ) );
  57.  *   Q_ASSERT( editor ); // This should not fail!
  58.  *   
  59.  *   // now use the editor.
  60.  *   editor->setRegExp("^kde$");
  61.  
  62.  *   // Finally insert the widget into the layout of its parent
  63.  *   layout->addWidget( editorWidget );
  64.  * }
  65.  * else {
  66.  *   // Don't offer the editor widget.
  67.  * }
  68.  * \endcode
  69.  *
  70.  */
  71. class KRegExpEditorInterface
  72. {
  73. public:
  74.   /**
  75.    * returns the regular expression of the editor in Qt3 QRegExp
  76.    * syntax. Note, there is also a 'regexp' Qt property available.
  77.    */
  78.   virtual QString regExp() const = 0;
  79.  
  80. protected:
  81. // These are signals: in classes that actually implement the interface.
  82.  
  83.   /**
  84.    * This signal tells whether undo is available.
  85.    */
  86.   virtual void canUndo( bool ) = 0;
  87.  
  88.   /**
  89.    * This signal tells whether redo is available.
  90.    */
  91.   virtual void canRedo( bool ) = 0;
  92.  
  93.   /**
  94.    * This signal is emited whenever the regular expression changes.
  95.    * The argument is true when the regular expression is different from
  96.    * the loaded regular expression and false when it is equal to the
  97.    * loaded regular expression.
  98.    */
  99.   virtual void changes( bool ) = 0;
  100.  
  101. public:
  102. // These are public slots: in classes that implement the interface.
  103.  
  104.  /**
  105.   * Set the regular expression for the editor. The syntax must be Qt3
  106.   * QRegExp syntax.
  107.   */
  108.   virtual void setRegExp( const QString ®exp ) = 0;
  109.   virtual void redo() = 0;
  110.   virtual void undo() = 0;
  111.  
  112.   /**
  113.    * Set text to use when showing matches. NOT IMPLEMENTED YET!
  114.    *   
  115.    * This method is not yet implemented. In later version of the widget
  116.    * this method will be used to give the widget a text to show matches of
  117.    * the regular expression on.
  118.    */
  119.   virtual void setMatchText( const QString& ) = 0;
  120.   
  121.   /**
  122.    * This method allows for future changes that will not break binary
  123.    * compatibility. DONT USE!
  124.    *   
  125.    * KDE has a policy of keeping binary compatibility for all major
  126.    * version of KDE. This means that new methods can not be added to this
  127.    * API before KDE version 4.0.
  128.    *
  129.    * This method is an escape door for that.
  130.    *   
  131.    * Conclusion: You should not use this method in this version of KDE!
  132.    */
  133.   virtual void doSomething( QString method, void* arguments ) = 0;
  134. };
  135.  
  136. #endif
  137.  
  138.